tinyexec

What is tinyexec?

The tinyexec npm package is a lightweight utility for executing shell commands in Node.js. It provides a simple and efficient way to run shell commands and capture their output, making it useful for scripting and automation tasks.

What are tinyexec's main functionalities?

Execute a simple command

This feature allows you to execute a simple shell command and capture its output. In this example, the 'echo' command is used to print 'Hello, World!' to the console.

const tinyexec = require('tinyexec');

(async () => {
  const result = await tinyexec('echo Hello, World!');
  console.log(result.stdout); // Outputs: Hello, World!
})();

Capture standard error

This feature allows you to capture the standard error output of a command. In this example, an attempt to run a nonexistent command results in an error, which is then captured and printed to the console.

const tinyexec = require('tinyexec');

(async () => {
  try {
    await tinyexec('nonexistent-command');
  } catch (error) {
    console.error(error.stderr); // Outputs the error message
  }
})();

Run a command with options

This feature allows you to run a command with additional options, such as specifying the working directory. In this example, the 'ls' command lists the files in the specified directory.

const tinyexec = require('tinyexec');

(async () => {
  const result = await tinyexec('ls', { cwd: '/path/to/directory' });
  console.log(result.stdout); // Outputs the list of files in the specified directory
})();

Other packages similar to tinyexec

child_process

The 'child_process' module is a built-in Node.js module that provides the ability to spawn child processes and execute shell commands. It offers more flexibility and control compared to tinyexec but requires more boilerplate code. It is suitable for more complex use cases where fine-grained control over the child process is needed.

execa

The 'execa' package is a modern alternative to the built-in 'child_process' module. It provides a more user-friendly API for executing shell commands and capturing their output. Execa offers additional features such as promise-based execution, better error handling, and support for streaming output. It is more feature-rich compared to tinyexec but also slightly larger in size.

shelljs

The 'shelljs' package is a portable Unix shell commands for Node.js. It provides a comprehensive set of shell commands that can be used in a cross-platform manner. Shelljs is more extensive and versatile compared to tinyexec, making it suitable for complex scripting tasks that require a wide range of shell functionalities.

README

tinyexec 📟

A minimal package for executing commands

This package was created to provide a minimal way of interacting with child processes without having to manually deal with streams, piping, etc.

Installing

$ npm i -S tinyexec

Usage

A process can be spawned and awaited like so:

import {x} from 'tinyexec';

const result = await x('ls', ['-l']);

// result.stdout - the stdout as a string
// result.stderr - the stderr as a string
// result.exitCode - the process exit code as a number

You may also iterate over the lines of output via an async loop:

import {x} from 'tinyexec';

const proc = x('ls', ['-l']);

for await (const line of proc) {
  // line will be from stderr/stdout in the order you'd see it in a term
}

Options

Options can be passed to have finer control over spawning of the process:

await x('ls', [], {
  timeout: 1000
});

The options object can have the following properties:

• signal - an AbortSignal to allow aborting of the execution
• timeout - time in milliseconds at which the process will be forceably killed
• persist - if true, the process will continue after the host exits
• stdin - another Result can be used as the input to this process
• nodeOptions - any valid options to node's underlying spawn function
• throwOnError - if true, non-zero exit codes will throw an error

Piping to another process

You can pipe a process to another via the pipe method:

const proc1 = x('ls', ['-l']);
const proc2 = proc1.pipe('grep', ['.js']);
const result = await proc2;

console.log(result.stdout);

pipe takes the same options as a regular execution. For example, you can pass a timeout to the pipe call:

proc1.pipe('grep', ['.js'], {
  timeout: 2000
});

Killing a process

You can kill the process via the kill method:

const proc = x('ls');

proc.kill();

// or with a signal
proc.kill('SIGHUP');

Node modules/binaries

By default, node's available binaries from node_modules will be accessible in your command.

For example, in a repo which has eslint installed:

await x('eslint', ['.']);

In this example, eslint will come from the locally installed node_modules.

Using an abort signal

An abort signal can be passed to a process in order to abort it at a later time. This will result in the process being killed and aborted being set to true.

const aborter = new AbortController();
const proc = x('node', ['./foo.mjs'], {
  signal: aborter.signal
});

// elsewhere...
aborter.abort();

await proc;

proc.aborted; // true
proc.killed; // true

API

Calling x(command[, args]) returns an awaitable Result which has the following API methods and properties available:

pipe(command[, args[, options]])

Pipes the current command to another. For example:

x('ls', ['-l'])
  .pipe('grep', ['js']);

The parameters are as follows:

• command - the command to execute (without any arguments)
• args - an array of arguments
• options - options object

process

The underlying node ChildProcess. For example:

const proc = x('ls');

proc.process; // ChildProcess;

kill([signal])

Kills the current process with the specified signal. By default, this will use the SIGTERM signal.

For example:

const proc = x('ls');

proc.kill();

pid

The current process ID. For example:

const proc = x('ls');

proc.pid; // number

aborted

Whether the process has been aborted or not (via the signal originally passed in the options object).

For example:

const proc = x('ls');

proc.aborted; // bool

killed

Whether the process has been killed or not (e.g. via kill() or an abort signal).

For example:

const proc = x('ls');

proc.killed; // bool

exitCode

The exit code received when the process completed execution.

For example:

const proc = x('ls');

proc.exitCode; // number (e.g. 1)

Comparison with other libraries

tinyexec aims to provide a lightweight layer on top of Node's own child_process API.

Some clear benefits compared to other libraries are that tinyexec will be much lighter, have a much smaller footprint and will have a less abstract interface (less "magic"). It will also have equal security and cross-platform support to popular alternatives.

There are various features other libraries include which we are unlikely to ever implement, as they would prevent us from providing a lightweight layer.

For example, if you'd like write scripts rather than individual commands, and prefer to use templating, we'd definitely recommend zx. zx is a much higher level library which does some of the same work tinyexec does but behind a template string interface.

Similarly, libraries like execa will provide helpers for various things like passing files as input to processes. We opt not to support features like this since many of them are easy to do yourself (using Node's own APIs).